<html dir="ltr" lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
	<meta charset="UTF-8"/>
	<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
	<title>GW2 Location Tracker ReadMe</title>
	<style>
		body {
			line-height: 0.5em;
			font-family: "Trebuchet MS", sans-serif;
			margin: 0.5em;
		}
		h1 {
			margin: 0.5em 0 0.5em 0;
		}
		h2, h3 {
			margin: 1.5em 0 0.5em 0;
		}
		h4 {
			margin: 0.25em 0;
		}
		p {
			margin: 0 1em;
		}
		pre{
			font-family: "Andale Mono", "Lucida Console", monospace;
		}
	</style>
</head>
<body>
<h1 id="top">Guild Wars 2 Location Tracker ReadMe</h1>

<p>
	Thanks for downloading and installing the GW2 Location Tracker. First of all it should be made clear that <font color="red">using this tool is not illegal and would not result in account bans</font>.
	In fact, it was encouraged by ArenaNet's Programmer <a href="https://forum-en.guildwars2.com/members/Cliff-Spradlin-3512" target="_blank">Cliff Spradlin</a> in
	<a href="https://forum-en.guildwars2.com/forum/community/api/Map-API-Mumble-Mashup/2256444" target="_blank">a post</a> on the official GW2 forums.
	How does it work? Guild Wars 2 supports	<a href="http://mumble.sourceforge.net/Positional-Audio" target="_blank">Mumble's positional audio</a> using the
	<a href="http://mumble.sourceforge.net/Link" target="_blank">Mumble Link API</a> which could also be used by any other program.
</p>

<h2>1. Getting started</h2>

<h3>1.1 Settings</h3>
<p>
	All of the following settings will be saved (when you've clicked "START") in <i>\Users\[Username]\AppData\Roaming\gw2maps\Gw2MapsConnectionInfo.txt</i> except for <i>Offline Mode</i> and <i>Tracking</i>.
</p>

<h4>URL (required)</h4>
<p>
	The URL of the location receiver. You may use <a href="http://gw2.chillerlan.net/examples/gw2location-receiver.php" target="_blank">http://gw2.chillerlan.net/examples/gw2location-receiver.php</a> for testing purposes
	(test data will be shown on <a href="http://gw2.chillerlan.net/examples/gw2location.html" target="_blank">this map</a>).
</p>

<h4>Account Name (required)</h4>
<p>
	Your <b>public</b> Guild Wars 2 display name - the one which is like <i>Name.1234</i>.	You can find it <a href="https://account.guildwars2.com/account" target="_blank">over here</a> on the official GW2 site.
	It will be used to identify your data and make sure it doesn't get overwritten in the database (using SQL REPLACE).
	Actually, you could type anything in there but since the GW2 display name is unique, you should use this.<br />
	PLEASE DO NOT ENTER YOUR GW2 E-MAIL OR ANY PERSONAL DATA IN THERE!
</p>

<h4>Guild Name</h4>
<p>
	Your exact Guild Name. The app will do a lookup to the <a href="https://api.guildwars2.com/v1/guild_details.json" target="_blank">GW2 guild API</a> to get the correct guild id which then will be sent to the specified URL.
</p>

<h4>Channel Key</h4>
<p>
	The channel key is a secret phrase which is shared between the members of a group to identify their members. You'll need to enter this key also on the website which shows the map in order to see that group.<br />
	PLEASE DO NOT ENTER YOUR GW2 PASSWORD OR ANY PERSONAL DATA IN THERE!
</p>

<h4>Update Time</h4>
<p>
	The interval in seconds for location updates to be sent to the receiver. Obviously.
</p>

<h4>Offline Mode</h4>
<p>
	When checked, the app will not establish a connection to the receiver and just output to the log screen instead.
</p>

<h4>Min Distance and Tracking</h4>
<p>
	These options depend on each other. When <i>Tracking</i> is checked, the app will stop sending continous data and sends only if the movement was beyond the specified value of <i>Min Distance</i> (which is ingame units).
	This is especially useful for track recording e.g. for wiki use.
</p>

<h4>Commander</h4>
<p>
	Sets a flag to identify a player as commander. (Yay, 100 gold saved! :D)
</p>

<h3>1.2 Characters</h3>
<p>
	Unfortunately, the Mumble Link data does not provide information about the characters profession, so this is done manually. Go to <i>Options &rarr; Character Settings </i> to add your characters.
	This menu is just straightforward: enter name, select profession, hit add and so on. Make sure the added name matches exactly your characters name, otherwise unknown profession (0) will be sent.
	Character settings will be saved in <i>\Users\[Username]\AppData\Roaming\gw2maps\Gw2MapsCharacters.txt</i>.
</p>

<h3>1.3 Log output</h3>
<p>
	The log output will print status messages as well as raw text responses from the location receiver. Nothing exciting here.
</p>


<h2>2. The CLI</h2>
<p>The Location sender has also a command line interface, here's a brief description of the switches and their usage. Note that you'll need to enclose a parameter's value in double quotes ( " ) if it contains whitespace.</p>

<h3>2.1 General parameters</h3>
<h4>-u</h4>
<p>
	<i>-u</i> defines the user's display name (see "Account Name" under "Getting started"). This parameter is required to establish a connection to a server in conjunction with <i>-s</i> or <i>-i/-p</i>.
</p>

<h4>-s</h4>
<p>
	<i>-s</i> defines the URL of the location receiver. Example:<br />
	<i>gw2maps -s http://gw2.chillerlan.net/examples/gw2location-receiver.php -u "Your Display Name.1234"</i>
</p>

<h4>-i and -p (not implemented yet)</h4>
<p>
	<i>-i</i> defines a server's IP address, <i>-p</i> specifies it's port. Can be used instead of <i>-s</i>. Example:<br />
	<i>gw2maps -i 127.0.0.1 -p 1234 -u "Your Display Name.1234"</i>
</p>

<h4>-start</h4>
<p>
	Once you've configured and saved the connection settings through the GUI, you can just use <i>-start</i> instead of <i>-s, -u</i> and other parameters. So you're fine with:<br />
	<i>gw2maps -start</i>
</p>

<h4>-h/-?/-help</h4>
<p>
	Either <i>-h, -?</i> or <i>-help</i> shows the info.
</p>

<h3>2.2 Optional parameters</h3>
<h4>-c</h4>
<p>
	<i>-c</i> defines the shared secret channel key
</p>

<h4>-g</h4>
<p>
	<i>-g</i> specifies a guild name
</p>

<h4>-t</h4>
<p>
	<i>-t</i> defines the update time interval
</p>

<h4>-tracking</h4>
<p>
	<i>-tracking</i> requires an integer value. If set it will override the update time interval (see "Min Distance and Tracking" under "Getting started")
</p>

<h3>2.3 Character management</h3>
<h4>-add and -prof</h4>
<p>
	<i>-add</i>	will add a character name with the profession <i>-prof</i> to the character list. Possible values for <i>-prof</i> are:
	<i>elementalist, engineer, guardian, mesmer, necromancer, ranger, thief, warrior</i>. Example:<br />
	<i>gw2maps -add "Your Characters Name" -prof thief</i>
</p>

<h4>-del</h4>
<p>
	<i>-del</i> removes a character from the list. Example:<br />
	<i>gw2maps -del "Your Characters Name"</i>
</p>


<h2>3. Use the data in your own projects</h2>
<h3>3.1 Receiving data</h3>
<p>
	The data you'll receive via a POST request (the field is named "data") is a simple JSON which could be easily parsed.
	There's a minimum amount of direct user input in it to minimize the risk of breaking web applications with XSS attacks or SQL injections.
	Here's some information on the data types to be expected:
</p>
<ul>
	<li><i>avatar_position</i>: array containing 2 elements of float type (you can find more information on recalculating the coordinates <a href="https://forum-en.guildwars2.com/forum/community/api/Event-Details-API-location-coordinates/2262330" target="_blank">on the forums</a>)</li>
	<li><i>avatar_front, profession, map_id, world_id, region_id, build</i>: unsigned integer</li>
	<li><i>server_ip</i>: the IP of the server the player is currently on, #^(?:\d{1,3}.){3}\d{1,3}$# </li>
	<li><i>name</i>: string, may contain non-ASCII characters, not necessarily harmful due to ArenaNet's character name guidelines</li>
	<li><i>account_name</i>: this is the only direct user input you'll receive, you may run a regex like #[a-z\s\d.]#i on it to make sure there's no illegal stuff in it</li>
	<li><i>guild_id</i>: uid of 36 bytes, #^[A-F\d]{8}-(:?[A-F\d]{4}-){3}[A-F\d]{12}$#</li>
	<li><i>channel_id</i>: sha1 hash, 40 bytes, #^[a-f\d]{40}$#i</li>
	<li><i>tracking, commander</i>: boolean</li>
</ul>

<pre>{
	"avatar_position": [-1504.04,11214.8],
	"avatar_front": 186,
	"name": "Cathea",
	"profession": 6,
	"map_id": 50,
	"world_id": 2005,
	"server_ip": "206.127.159.181",
	"region_id" : 2,
	"build": 20941,
	"account_name": "smiley.1438",
	"guild_id": "75FD83CF-0C45-4834-BC4C-097F93A487AF",
	"channel_id": "76cbfee2dd33d5d34bfecc274ea5e766e11ead92",
	"tracking": 0,
	"commander": 0
}</pre>

<p>
	You can find an example implementation in PHP/MySQL over here on GitHub: <a href="https://github.com/codemasher/gw2api-tools/blob/master/examples/gw2location-receiver.php" target="_blank">https://github.com/codemasher/gw2api-tools/blob/master/examples/gw2location-receiver.php</a>.
</p>

<h3>3.2 Source code</h3>
<p>
	You can find the source code of the location tracker in [installation folder]\source along with some example maps and SQL files. For the latest source of the location tracker have a look at the
	<a href="https://gw2apicpp.codeplex.com/SourceControl/latest" target="_blank">CodePlex repo</a> and for the latest backend code look on the
	<a href="https://github.com/codemasher/gw2api-tools/">GitHub repo</a>.
</p>

<center style="text-align: center; margin: 2em;">
	<a href="https://gw2apicpp.codeplex.com/" target="_blank">Guild Wars 2 API C/C++ Library Project</a> &copy;	<a href="https://forum-en.guildwars2.com/members/Heimdall-4510" target="_blank">Heimdall.4510</a><br />
	<a href="https://github.com/codemasher/gw2api-tools/" target="_blank">GW2 API Tools</a> &copy; <a href="https://forum-en.guildwars2.com/members/smiley-1438" target="_blank">smiley.1438</a>
</center>

</body>
</html>